/*!
 * \file shutdown_policies.hpp
 * \brief 关闭策略
 *
 * \details 此文件包含thread_pool的关闭策略。
 *          
 *          关闭策略控制线程池从不再被引用时起的行为。
 *          
 *          提供的关闭策略包括：
 *          - wait_for_all_tasks：等待所有任务完成及工作线程终止
 *          - wait_for_active_tasks：等待活动任务完成及工作线程终止
 *          - immediately：立即关闭，不等待任务或工作线程终止
 *          
 *          不同的关闭策略适用于不同的应用场景，提供了从优雅关闭
 *          到强制关闭的各种选择。
 *
 * Copyright (c) 2005-2007 Philipp Henkel
 *
 * Use, modification, and distribution are  subject to the
 * Boost Software License, Version 1.0. (See accompanying  file
 * LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 *
 * http://threadpool.sourceforge.net
 *
 */

#ifndef THREADPOOL_SHUTDOWN_POLICIES_HPP_INCLUDED
#define THREADPOOL_SHUTDOWN_POLICIES_HPP_INCLUDED

/// threadpool命名空间包含线程池和相关实用类
namespace boost { namespace threadpool
{

  /*!
   * \brief 等待所有任务完成及工作线程终止的关闭策略
   *
   * \details 此策略会等待队列中所有任务（包括待执行的任务）完成，
   *          然后等待所有工作线程终止。
   *          
   *          适用场景：
   *          - 需要确保所有任务都被处理的场景
   *          - 数据一致性要求高的应用
   *          - 批处理任务的完整执行
   *          
   *          特点：
   *          - 最安全的关闭方式
   *          - 可能需要较长的关闭时间
   *          - 保证任务完整性
   *
   * \tparam Pool 线程池的核心类型
   */ 
  template<typename Pool>
  class wait_for_all_tasks
  {
  public:
    /*!
     * \brief 执行关闭操作
     * \param pool 要关闭的线程池引用
     * 
     * \details 先等待所有任务完成，然后终止所有工作线程并等待其结束
     */
    static void shutdown(Pool& pool)
    {
      pool.wait();
      pool.terminate_all_workers(true);
    }
  };

  /*!
   * \brief 等待活动任务完成及工作线程终止的关闭策略
   *
   * \details 此策略会清除队列中待执行的任务，只等待当前正在执行的
   *          活动任务完成，然后等待所有工作线程终止。
   *          
   *          适用场景：
   *          - 需要快速关闭但保证当前任务完成
   *          - 队列中有大量待执行任务时的优雅关闭
   *          - 对关闭时间有要求的应用
   *          
   *          特点：
   *          - 平衡了关闭速度和任务完整性
   *          - 会丢弃未开始执行的任务
   *          - 保证正在执行的任务完成
   *
   * \tparam Pool 线程池的核心类型
   */ 
  template<typename Pool>
  class wait_for_active_tasks
  {
  public:
    /*!
     * \brief 执行关闭操作
     * \param pool 要关闭的线程池引用
     * 
     * \details 先清除待执行任务，等待活动任务完成，然后终止所有工作线程并等待其结束
     */
    static void shutdown(Pool& pool)
    {
      pool.clear();
      pool.wait();
      pool.terminate_all_workers(true);
    }
  };

  /*!
   * \brief 立即关闭策略，不等待任务或工作线程终止
   *
   * \details 此策略不等待任何任务完成。尽管如此，所有活动任务
   *          仍将被完全处理。
   *          
   *          适用场景：
   *          - 需要快速关闭的紧急情况
   *          - 对任务完整性要求不高的应用
   *          - 系统资源紧张时的强制关闭
   *          
   *          特点：
   *          - 最快的关闭方式
   *          - 可能导致任务丢失
   *          - 不等待工作线程完全终止
   *
   * \tparam Pool 线程池的核心类型
   */ 
  template<typename Pool>
  class immediately
  {
  public:
    /*!
     * \brief 执行关闭操作
     * \param pool 要关闭的线程池引用
     * 
     * \details 清除所有待执行任务，立即终止所有工作线程但不等待其结束
     */
    static void shutdown(Pool& pool)
    {
      pool.clear();
      pool.terminate_all_workers(false);
    }
  };

} } // namespace boost::threadpool

#endif // THREADPOOL_SHUTDOWN_POLICIES_HPP_INCLUDED
